home *** CD-ROM | disk | FTP | other *** search
/ CU Amiga Super CD-ROM 18 / CU Amiga Magazine's Super CD-ROM 18 (1997)(EMAP Images)(GB)[!][issue 1998-01].iso / CUCD / Online / hsc / docs-source / features / exec.hsc < prev    next >
Encoding:
Text File  |  1997-10-20  |  7.9 KB  |  217 lines

  1. <WEBPAGE chapter="hsc - " title="Execute Shell Commands"
  2.          PREV="prefs.html"
  3.          NEXT=":project/index.html">
  4.  
  5. <P>You can invoke shell-commands during processing of a hsc source. The
  6. output of the command can be assigned to an special attribute or
  7. immediately being included into the document. This can be useful to
  8. include data from external applications (like databases), prepared
  9. by scripts (eg. Rexx), which of course you have to write yourself.</P>
  10.  
  11. <P>This functionality is provided by the hsc tag <TG>$exec</TG></P>
  12.  
  13. <H2>Possible Attributes</H2>
  14.  
  15. <DL>
  16. <DT><CODE>COMMAND:string/required</CODE>
  17. <DD>Specifies command to be executed. This attribute is required
  18.  
  19. <DT><CODE>INCLUDE:bool</CODE>
  20. <DD>If this attribute occurs, the output the command sends to
  21.     <stdout> (or the filename specified with <CODE>FILE</CODE>)
  22.     is included in the document.
  23.  
  24. <DT><CODE>ATTRIBUTE:string</CODE>
  25. <DD>Using this attribute, you can select an attribute you've
  26.     created before using <ln_define> to store the data the
  27.     command sends to <stdout>.
  28.  
  29. <DT><CODE>FILE:string</CODE>
  30. <DD>Specifies filename where the command is expected to store
  31.     the output. The filename is relative to the source-directory.
  32.     If this attribute is not set, <hsc> will assume the command
  33.     to output to <stdout> and will redirect the output to a 
  34.     temporary file. This attribute is only useful if you have
  35.     also set at least one of <CODE>INCLUDE</CODE> or 
  36.     <CODE>ATTRIBUTE</CODE>
  37.  
  38. <DT><CODE>TEMPORARY:bool</CODE>
  39. <DD>This attribute has the same meaning as within <ln_include>. Note that
  40.     it can be reasonable to specify it, even if you set a specific 
  41.     output-file, and not only for temporary-files created by <hsc>.
  42.  
  43. <DT><CODE>REMOVE:enum("auto|on|off")="auto"</CODE>
  44. <DD>This attribute tells <hsc> what to do with the output-file after
  45.     all data have been read. If you set it to 
  46.     <CODE>REMOVE="off"</CODE>, the file will be left untouched. If no one
  47.     else is going to remove it, it will continue to exist until 
  48.     doomsday or the next head-crash.
  49.  
  50.     <P>If you didn't specify an output filename (using <CODE>FILE</CODE>),
  51.     this  can clutter your temporary-directory (usually "<FILE>t:</FILE>")
  52.     with loads of files having strange names like 
  53.     "<FILE>hsc0x321764.tmp</FILE>".</P>
  54.     <P>To avoid this, you can set <CODE>REMOVE="on"</CODE>, so the output-file
  55.     will always be removed.</P>
  56.  
  57.     <P>By default, <CODE>REMOVE="auto"</CODE> is set. This will remove the
  58.     file, if <CODE>TEMPORARY</CODE> has been enabled, and - if 
  59.     <CODE>INCLUDE</CODE> has been activated, too - no messages
  60.     showed up during including the file.</P>
  61.  
  62.     <STRONG>Note</STRONG>: Never trust freeware-programmers when they
  63.     start removing your files. So never use <TG>$exec</TG> on important
  64.     data without any backup, and always use <CODE>REMOVE="off"</CODE>
  65.     if your data are not really completely temporary.
  66. </DL>
  67.  
  68. <P>Additionally, you can use all attributes of <TG>$include</TG> that change
  69. the appearance of the included data, like <CODE>PRE</CODE>,
  70. <CODE>SOURCE</CODE> etc. - Of course, this only makes sense if the
  71. <CODE>INCLUDE</CODE>-attribute has been set.</P>
  72.  
  73. <P>You can set both <CODE>INCLUDE</CODE> and <CODE>ATTRIBUTE</CODE> with
  74. one call to <TG>$exec</TG>.</P>
  75.  
  76. <H2>Examples</H2>
  77.  
  78. <DL>
  79. <DT><TG>$exec COMMAND="dpaint"</TG>
  80. <DD>Invokes Deluxe-Paint. Now you can paint whatever you like.
  81.     When you quit the program, <hsc> will continue to process 
  82.     it's source. Note that this is not a very useful example.
  83. <DT><TG>$exec COMMAND="list #?.hsc" TEMPORARY INCLUDE SOURCE PRE</TG>
  84. <DD>List all hsc-sources in the current directory and include
  85.     this list into the current document. The output of the
  86.     <KBD>list</KBD>-command is redirected to a temporary file,
  87.     which is removed afterwards.
  88. <DT><TG>$exec COMMAND="echo Hello! >echo.tmp" TEMPORARY INCLUDE FILE="echo.tmp"</TG>
  89. <DD>List all hsc-sources in the current directory and include
  90.     this list into the current document. The output of the
  91.     <KBD>list</KBD>-command is obviously redirected to a file 
  92.     called <FILE>echo.tmp</FILE>, which <hsc> tries to read because of
  93.     the <CODE>FILE</CODE>-attribute.
  94. <DT><TG>$define output:string</TG><BR>
  95.     <TG>$exec COMMAND="list #?.hsc" ATTRIBUTE="output"</TG>
  96. <DD>List all *.hsc-files in current directory and assign output to
  97.     the attribute <CODE>output</CODE>; no data are included into the 
  98.     current document.
  99. </DL>
  100.  
  101. <H2>A More Complex Example</H2>
  102.  
  103. If you want to create a portable hsc source to insert a listing of a
  104. directory, you could try something like this:
  105.  
  106. <$include FILE="exmpl/exec.hsc" SOURCE PRE>
  107.  
  108. And the data created by this code sequence would look like this:
  109.  
  110. <$include FILE="exmpl/exec.hsc">
  111.  
  112. <H2>Computing Complex Data</H2>
  113.  
  114. <$define snc.rex:string="StripNastyChars.rexx">
  115. <$define snc.hsc:string="StripNastyChars.hsc">
  116. <$macro snc.rex><file><(snc.rex)></file></$macro>
  117. <$macro snc.hsc><file><(snc.hsc)></file></$macro>
  118.  
  119. <P>As <hsc> is only a simple preprocessor, but not a programming language, it
  120. can not do certain things. For example, there are no string functions. But
  121. you can use external commands to gain the same result.</P>
  122.  
  123. <P>The Rexx-script <grafflwerk href=(snc.rex)> together with
  124. <grafflwerk href=(snc.hsc)> shows how to strip all but alpha numeric
  125. characters from a given string.</P>
  126.  
  127. To better understand what <snc.rex>, you can first try to call it from
  128. the command line. Set your working directory to <grafflwerk>, and
  129. type:
  130.  
  131. <PRE>rx <(snc.rex)> bla:sülz:fasel</PRE>
  132. results in
  133. <PRE>blaslzfasel</PRE>
  134.  
  135. If you tried this yourself, you maybe noticed that the Rexx-script does not
  136. output a linefeed at the end of line. This is done by avoiding to use
  137.  
  138. <PRE>SAY stripped</PRE>
  139.  
  140. to display the converted data. Instead, you will find a
  141.  
  142. <PRE>call WriteCH(stdout, stripped)</PRE>
  143.  
  144. This simply is because <snc.hsc> assigns the output of this script to
  145. a target attribute called <CODE>clean-data</CODE> by means of
  146.  
  147. <$source pre>
  148. <$exec command=("rx StripNastyChars.rexx " + nasty-data) ATTRIBUTE=clean-data>
  149. </$source>
  150.  
  151. Because of obvious reasons, the linefeed character created by
  152. <CODE>SAY</CODE> would be unwanted in the value of the target
  153. attribute. Therefor, the interesting part of the created html-document
  154. will look like:
  155.  
  156. <PRE>
  157. Converted "This#Text|Contains!Ñâ§ïÿ/Characters"
  158. to        "ThisTextContainsCharacters".
  159. </PRE>
  160.  
  161. It should be easy for you to put this functionality in a macro.
  162.  
  163. <H2>Problems</H2>
  164.  
  165. <P>Technically speaking, <hsc> redirects the output of you command by
  166. appending a " <CODE>></CODE><I>filename</I>" to the command-string.
  167. For example, if you called</P>
  168.  
  169. <$source PRE>
  170. <$exec COMMAND="list #?.hsc" INCLUDE>
  171. </$source>
  172. <P><hsc> will invoke the command like</P>
  173.  
  174. <$source PRE>
  175. list #?.hsc >hsc0x321764.tmp
  176. </$source>
  177.  
  178. <P>with <FILE>hsc0x321764.tmp</FILE> chosen as temporary output file by
  179. <hsc>. If you specify the <CODE>FILE</CODE> attribute, you tell <hsc>
  180. where to expect the output. But now you are responsible to redirect 
  181. it yourself. For example,</P>
  182.  
  183. <$source PRE>
  184. <$exec COMMAND="list #?.hsc >list.tmp"   INCLUDE FILE="list.tmp">
  185. <$exec COMMAND="list #?.hsc TO list.tmp" INCLUDE FILE="list.tmp">
  186. </$source>
  187.  
  188. <P>will both create an output in <FILE>list.tmp</FILE>, where <hsc> will
  189. also look for it. But the next one will fail:</P>
  190.  
  191. <$source PRE>
  192. <$exec COMMAND="list #?.hsc >list.tmp" FILE="tmp.list">
  193. </$source>
  194.  
  195. <P>The reason is obvious: The command outputs to <FILE>list.tmp</FILE>,
  196. but <hsc> tries to read <FILE>tmp.list</FILE>, which most likely will
  197. not exist.</P>
  198.  
  199. <P>Another problem will occur, if you redirect the output yourself
  200. within the command call, but do not specify the 
  201. <CODE>FILE</CODE>-attribute: <hsc> will try to redirect the output twice: 
  202. For example,</P>
  203.  
  204. <$source PRE>
  205. <$exec COMMAND="list #?.hsc >list.tmp" INCLUDE>
  206. </$source>
  207.  
  208. <P>will try to invoke something like</P>
  209.  
  210. <$source PRE>
  211. list #?.hsc >list.tmp >hsc0x321764.tmp
  212. </$source>
  213.  
  214. <P>The behavior of this call is system dependent, but there's a general
  215. statement on this topic: it most likely won't work.</P>
  216. </WEBPAGE>
  217.